home *** CD-ROM | disk | FTP | other *** search
/ Freelog 22 / freelog 22.iso / Prog / Djgpp / PDCUR24B.ZIP / contrib / pdcur24 / doc / x11.man < prev   
Encoding:
Text File  |  1999-10-20  |  8.9 KB  |  246 lines
  1. /*man-start*********************************************************************
  2.  
  3. Introduction:
  4. ------------
  5.  
  6.  XCurses uses the System V IPC shared memory facility for sharing data
  7.  between the curses program and the child process created to manage the
  8.  X stuff. XCurses also uses sockets for communication between the
  9.  processes.
  10.  
  11.  To use XCurses with an existing curses program, you need to make two
  12.  changes to your code.
  13.  
  14.  The first is the addition of a definition of the program name as a
  15.  global char pointer. eg.
  16.  
  17. #ifdef XCURSES
  18.  char *XCursesProgramName="sample";
  19. #endif
  20.  
  21.  This name is used as the title of the X window, and for defining X
  22.  resources specific to your program.
  23.  
  24.  The second is a call to XCursesExit() just before exiting from your
  25.  program. eg.
  26.  
  27. #ifdef XCURSES
  28.  XCursesExit();
  29. #endif
  30.  exit(0);
  31.  
  32.  This call is required to enable the child X process to shut down cleanly
  33.  and free up the shared memory it used.
  34.  
  35.  When compiling your curses application, you need to add -DXCURSES.
  36.  
  37.  XCurses programs use the X Toolkit Intrinsics libraries.  You will need
  38.  to link your code with the following libraries under X11R5:
  39.     Xaw Xmu Xt X11
  40.  
  41.  and under X11R6:
  42.     Xaw Xmu Xt X11 SM ICE Xext
  43.  
  44.  The best method of determining which libraries you need, is to
  45.  compile one of the demo programs and take note of the libraries
  46.  it uses.
  47.  
  48. Here be Dragons!
  49. ----------------
  50.  
  51.  Be aware that curses programs that expect to have a normal tty underneath
  52.  them will be very disappointed! Output directed to stdout after a call
  53.  to system() (maybe even exec()) will go to the xterm that invoked the
  54.  XCurses application, or to the console if not invoked directly from an
  55.  xterm. Similarly, stdin will expect its input from the same place as
  56.  stdout.
  57.  
  58.  This situation is not desirable, but I know of no simple way to get
  59.  around this.
  60.  
  61.  
  62. X Resources:
  63. -----------
  64.  
  65. XCurses recognises the following resources:
  66.  
  67.     lines
  68.     cols
  69.     normalFont
  70.     boldFont
  71.     pointer
  72.     pointerForeColor
  73.     pointerBackColor
  74.     cursorColor
  75.     colorBlack
  76.     colorRed
  77.     colorGreen
  78.     colorYellow
  79.     colorBlue
  80.     colorMagenta
  81.     colorCyan
  82.     colorWhite
  83.     bitmap
  84.     translations
  85.     shmmin
  86.     borderWidth
  87.     borderColor
  88.     clickPeriod
  89.     doubleClickPeriod
  90.     composeKey
  91.  
  92. lines:             specifies the number of lines the "screen" will have
  93.                    Directly equates to LINES
  94.                    There is no theoretical maximum.
  95.                    The minimum value must be 2.
  96.                    Default:        24
  97.  
  98. cols:              specifies the number of columns the "screen" will have
  99.                    Directly equates to COLS
  100.                    There is no theoretical maximum.
  101.                    The minimum value must be 2.
  102.                    Default:        80
  103.  
  104. normalFont:        the name of a fixed width font, used for A_NORMAL attribute
  105.                    Default:        7x13
  106.  
  107. boldFont:          the name of a fixed width font, used for A_BOLD attribute
  108.                    Default:        7x13bold
  109.  
  110.                    NB. The dimensions of font and boldFont MUST be the same.
  111.  
  112. pointer:           the name of a valid pointer cursor
  113.                    Default:        xterm
  114.  
  115. pointerForeColor:  the foreground colour of the pointer
  116.                    Default:        black
  117.  
  118. pointerBackColor:  the background colour of the pointer
  119.                    Default:        white
  120.  
  121. cursorColor:       the colour of the text cursor
  122.                    Default:        Red
  123.                    *** This resource is now obsolete and is ignored ***
  124.  
  125. colorBlack:        the color of the COLOR_BLACK attribute
  126. colorRed           the color of the COLOR_RED attribute
  127. colorGreen         the color of the COLOR_GREEN attribute
  128. colorYellow        the color of the COLOR_YELLOW attribute
  129. colorBlue          the color of the COLOR_BLUE attribute
  130. colorMagenta       the color of the COLOR_MAGENTA attribute
  131. colorCyan          the color of the COLOR_CYAN attribute
  132. colorWhite         the color of the COLOR_WHITE attribute
  133.                    Defaults are obvious :)
  134.  
  135. bitmap:            the name of a valid pixmap file of depth 1 used for
  136.                    the application's icon
  137.                    Default:        a 32x32 or 64x64 pixmap depending on the 
  138.                                    window manager
  139.  
  140. translations:      Translations enable the user to customise the
  141.                    action that occurs when a key, combination of keys, or a
  142.                    button is pressed.  The translations in XCurses are similar
  143.                    in function and definition to translations used by xterm.
  144.                    Defaults:
  145.                         <Key>:                    XCursesKeyPress()
  146.                         <Btn1Down>:               XCursesButton()
  147.                         !Ctrl <Btn2Down>:         XCursesButton()
  148.                         <Btn2Down>,<Btn2Up>:      XCursesPasteSelection()
  149.                         <Btn3Down>:               XCursesButton()
  150.                         <Btn1Up>:                 XCursesButton()
  151.                         <Btn3Up>:                 XCursesButton()
  152.                         <BtnMotion>:              XCursesButton()
  153.  
  154.                    The most useful action for KeyPress translations is string().
  155.                    The argument to the string() action can be either a string or
  156.                    a hex representation of a character. eg. string(0x1b) will
  157.                    result in the ASCII escape character to be sent to the 
  158.                    XCurses application. string("[11~") will result in [ 1 1 ~ 
  159.                    being sent, as seperate keystokes to the XCurses application.
  160.  
  161. shmmin:            On most systems, there are two Unix kernel parameters that 
  162.                    determine the allowable size of a shared memory segment. These
  163.                    parameters are usually something like SHMMIN and SHMMAX. To use
  164.                    shared memory, a program must allocate a segment of shared memory
  165.                    that is between these two values.  Usually these values are
  166.                    like 1 for SHMMIN and some large number for SHMMAX. Sometimes
  167.                    the Unix kernel is configured to have a value of SHMMIN that is
  168.                    bigger than the size of one of the shared memory segments that
  169.                    XCurses uses. On these systems an error message like:
  170.  
  171.                      Cannot allocate shared memory for SCREEN: Invalid argument
  172.  
  173.                    will result. To overcome this problem, this XCurses resource
  174.                    should be set to the kernel value for SHMMIN. This ensures that
  175.                    a shared memory segment will always be bigger than the kernel
  176.                    value for SHMMIN (and hopefully less than SHMMAX!)
  177.  
  178.                    Default:        0
  179.  
  180. borderColor:       the colour of the border around the screen
  181.                    Default:        Black
  182.  
  183. borderWidth:       the width in pixels of the border around the screen
  184.                    Default:        0
  185.  
  186. clickPeriod:       the period (in milliseconds) between a button press
  187.                    and a button release that determines if a click
  188.                    of a button has occurred.
  189.                    Default:        100
  190.  
  191. doubleClickPeriod: the period (in milliseconds) between two button
  192.                    press events that determines if a double click
  193.                    of a button has occurred.
  194.                    Default:        200
  195.  
  196. composeKey:        the name of the X key that defines the "compose key" which
  197.                    is used to enter characters in the Latin-1 character set above
  198.                    0xA0.
  199.                    Generally this key will be one of the X "modifier" keys, like
  200.                    Alt_L, Meta_R etc. but can be a "normal" key like F1.  Try to 
  201.                    While in "compose key" mode, the text cursor will appear as
  202.                    a hollow rectangle.
  203.                    See the file latin-1.man for details on compose key usage.
  204.                    Default:        No key is defined
  205.  
  206. Using Resources:
  207. ---------------
  208.  
  209.  All XCurses applications have a top-level class name of "XCurses".
  210.  The top-level widget name for each XCurses application is the
  211.  same as that defined by the XCursesProgram name in the application's
  212.  main source module.
  213.  
  214.  An example of an XCurses app-defaults or .Xdefaults file might be:
  215.  
  216. !
  217. ! resources for XCurses class of programs
  218. !
  219. XCurses*lines:  30
  220. XCurses*cols:   80
  221. XCurses*normalFont:     9x13
  222. XCurses*boldFont:       9x13bold
  223. XCurses*bitmap: /tmp/xcurses.xbm
  224. XCurses*pointer: top_left_arrow
  225. !
  226. ! resources for testcurs - XCurses
  227. !
  228. testcurs.colorRed:      orange
  229. testcurs.colorBlack:    midnightblue
  230. testcurs.lines: 25
  231. *testcurs.Translations: #override \n \
  232.   <Key>F12:  string(0x1b) string("[11~") \n
  233. !
  234. ! resources for THE - XCurses
  235. !
  236. the.normalFont: 9x15
  237. the.boldFont:   9x15bold
  238. the.lines:      40
  239. the.cols:       86
  240. the.pointer:    xterm
  241. the.pointerForeColor: black
  242. the.pointerBackColor: black
  243. the.bitmap:     /home/mark/the/the64.xbm
  244.  
  245. **man-end**********************************************************************/
  246.